<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>gimpexport: GIMP 3 Library Reference Manual</title>
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
<link rel="home" href="index.html" title="GIMP 3 Library Reference Manual">
<link rel="up" href="libgimpui.html" title="Part II. GIMP User Interface Library">
<link rel="prev" href="libgimp3-gimpui.html" title="gimpui">
<link rel="next" href="GimpDrawablePreview.html" title="GimpDrawablePreview">
<meta name="generator" content="GTK-Doc V1.33.0 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts">
<a href="#" class="shortcut">Top</a><span id="nav_description">  <span class="dim">|</span> 
                  <a href="#libgimp3-gimpexport.description" class="shortcut">Description</a></span>
</td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><a accesskey="u" href="libgimpui.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
<td><a accesskey="p" href="libgimp3-gimpui.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="GimpDrawablePreview.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="refentry">
<a name="libgimp3-gimpexport"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2><span class="refentrytitle"><a name="libgimp3-gimpexport.top_of_page"></a>gimpexport</span></h2>
<p>gimpexport — Export an image before it is saved.</p>
</td>
<td class="gallery_image" valign="top" align="right"></td>
</tr></table></div>
<div class="refsect1">
<a name="libgimp3-gimpexport.functions"></a><h2>Functions</h2>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="functions_proto_type">
<col class="functions_proto_name">
</colgroup>
<tbody>
<tr>
<td class="function_type">
<a class="link" href="libgimp3-gimpexport.html#GimpExportReturn" title="enum GimpExportReturn"><span class="returnvalue">GimpExportReturn</span></a>
</td>
<td class="function_name">
<a class="link" href="libgimp3-gimpexport.html#gimp-export-image" title="gimp_export_image ()">gimp_export_image</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<a href="https://developer.gnome.org/gtk3/GtkWidget.html#GtkWidget-struct"><span class="returnvalue">GtkWidget</span></a> *
</td>
<td class="function_name">
<a class="link" href="libgimp3-gimpexport.html#gimp-export-dialog-new" title="gimp_export_dialog_new ()">gimp_export_dialog_new</a> <span class="c_punctuation">()</span>
</td>
</tr>
<tr>
<td class="function_type">
<a href="https://developer.gnome.org/gtk3/GtkWidget.html#GtkWidget-struct"><span class="returnvalue">GtkWidget</span></a> *
</td>
<td class="function_name">
<a class="link" href="libgimp3-gimpexport.html#gimp-export-dialog-get-content-area" title="gimp_export_dialog_get_content_area ()">gimp_export_dialog_get_content_area</a> <span class="c_punctuation">()</span>
</td>
</tr>
</tbody>
</table></div>
</div>
<div class="refsect1">
<a name="libgimp3-gimpexport.other"></a><h2>Types and Values</h2>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="other_proto_type">
<col class="other_proto_name">
</colgroup>
<tbody>
<tr>
<td class="datatype_keyword">enum</td>
<td class="function_name"><a class="link" href="libgimp3-gimpexport.html#GimpExportCapabilities" title="enum GimpExportCapabilities">GimpExportCapabilities</a></td>
</tr>
<tr>
<td class="datatype_keyword">enum</td>
<td class="function_name"><a class="link" href="libgimp3-gimpexport.html#GimpExportReturn" title="enum GimpExportReturn">GimpExportReturn</a></td>
</tr>
</tbody>
</table></div>
</div>
<div class="refsect1">
<a name="libgimp3-gimpexport.description"></a><h2>Description</h2>
<p>This function should be called by all save_plugins unless they are
able to save all image formats GIMP knows about. It takes care of
asking the user if she wishes to export the image to a format the
save_plugin can handle. It then performs the necessary conversions
(e.g. Flatten) on a copy of the image so that the image can be
saved without changing the original image.</p>
<p>The capabilities of the save_plugin are specified by combining
<a class="link" href="libgimp3-gimpexport.html#GimpExportCapabilities" title="enum GimpExportCapabilities"><span class="type">GimpExportCapabilities</span></a> using a bitwise OR.</p>
<p>Make sure you have initialized GTK+ before you call this function
as it will most probably have to open a dialog.</p>
</div>
<div class="refsect1">
<a name="libgimp3-gimpexport.functions_details"></a><h2>Functions</h2>
<div class="refsect2">
<a name="gimp-export-image"></a><h3>gimp_export_image ()</h3>
<pre class="programlisting"><a class="link" href="libgimp3-gimpexport.html#GimpExportReturn" title="enum GimpExportReturn"><span class="returnvalue">GimpExportReturn</span></a>
gimp_export_image (<em class="parameter"><code><a class="link" href="GimpImage.html" title="gimpimage"><span class="type">GimpImage</span></a> **image</code></em>,
                   <em class="parameter"><code><span class="type">gint</span> *n_drawables</code></em>,
                   <em class="parameter"><code><a class="link" href="GimpDrawable.html" title="gimpdrawable"><span class="type">GimpDrawable</span></a> ***drawables</code></em>,
                   <em class="parameter"><code>const <span class="type">gchar</span> *format_name</code></em>,
                   <em class="parameter"><code><a class="link" href="libgimp3-gimpexport.html#GimpExportCapabilities" title="enum GimpExportCapabilities"><span class="type">GimpExportCapabilities</span></a> capabilities</code></em>);</pre>
<p>Takes an image and a drawable to be saved together with a
description of the capabilities of the image_format. If the
type of image doesn't match the capabilities of the format
a dialog is opened that informs the user that the image has
to be exported and offers to do the necessary conversions.</p>
<p>If the user chooses to export the image, a copy is created.
This copy is then converted, <em class="parameter"><code>image</code></em>
 and <em class="parameter"><code>drawables</code></em>
 are changed to
point to the new image and the procedure returns GIMP_EXPORT_EXPORT.
The save_plugin has to take care of deleting the created image using
<a class="link" href="GimpImage.html#gimp-image-delete" title="gimp_image_delete ()"><code class="function">gimp_image_delete()</code></a> and the drawables list with <code class="function">g_free()</code> once the
image has been saved.</p>
<p>If the user chooses to Ignore the export problem, <em class="parameter"><code>image</code></em>
 and
<em class="parameter"><code>drawables</code></em>
 are not altered, GIMP_EXPORT_IGNORE is returned and the
save_plugin should try to save the original image. If the user
chooses Cancel, GIMP_EXPORT_CANCEL is returned and the save_plugin
should quit itself with status <a href="../html/libgimpbase3-gimpbaseenums.html#GIMP-PDB-CANCEL:CAPS"><code class="literal">GIMP_PDB_CANCEL</code></a>.</p>
<p>If <em class="parameter"><code>format_name</code></em>
 is NULL, no dialogs will be shown and this function
will behave as if the user clicked on the 'Export' button, if a
dialog would have been shown.</p>
<div class="refsect3">
<a name="gimp-export-image.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody>
<tr>
<td class="parameter_name"><p>image</p></td>
<td class="parameter_description"><p>Pointer to the image.</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>n_drawables</p></td>
<td class="parameter_description"><p>Size of <em class="parameter"><code>drawables</code></em>
.</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>drawables</p></td>
<td class="parameter_description"><p>Array of pointers to drawables.</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>format_name</p></td>
<td class="parameter_description"><p>The (short) name of the image_format (e.g. JPEG or GIF).</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>capabilities</p></td>
<td class="parameter_description"><p>What can the image_format do?</p></td>
<td class="parameter_annotations"> </td>
</tr>
</tbody>
</table></div>
</div>
<div class="refsect3">
<a name="gimp-export-image.returns"></a><h4>Returns</h4>
<p> An enum of <a class="link" href="libgimp3-gimpexport.html#GimpExportReturn" title="enum GimpExportReturn"><span class="type">GimpExportReturn</span></a> describing the user_action.</p>
</div>
</div>
<hr>
<div class="refsect2">
<a name="gimp-export-dialog-new"></a><h3>gimp_export_dialog_new ()</h3>
<pre class="programlisting"><a href="https://developer.gnome.org/gtk3/GtkWidget.html#GtkWidget-struct"><span class="returnvalue">GtkWidget</span></a> *
gimp_export_dialog_new (<em class="parameter"><code>const <span class="type">gchar</span> *format_name</code></em>,
                        <em class="parameter"><code>const <span class="type">gchar</span> *role</code></em>,
                        <em class="parameter"><code>const <span class="type">gchar</span> *help_id</code></em>);</pre>
<p>Creates a new export dialog. All file plug-ins should use this
dialog to get a consistent look on the export dialogs. Use
<a class="link" href="libgimp3-gimpexport.html#gimp-export-dialog-get-content-area" title="gimp_export_dialog_get_content_area ()"><code class="function">gimp_export_dialog_get_content_area()</code></a> to get a vertical <a href="https://developer.gnome.org/gtk3/GtkBox.html#GtkBox-struct"><span class="type">GtkBox</span></a> to be
filled with export options. The export dialog is a wrapped
<a href="../html/GimpDialog.html#GimpDialog-struct"><span class="type">GimpDialog</span></a>.</p>
<p>The dialog response when the user clicks on the Export button is
<a href="https://developer.gnome.org/gtk3/GtkDialog.html#GTK-RESPONSE-OK:CAPS"><code class="literal">GTK_RESPONSE_OK</code></a>, and when the Cancel button is clicked it is
<a href="https://developer.gnome.org/gtk3/GtkDialog.html#GTK-RESPONSE-CANCEL:CAPS"><code class="literal">GTK_RESPONSE_CANCEL</code></a>.</p>
<div class="refsect3">
<a name="gimp-export-dialog-new.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody>
<tr>
<td class="parameter_name"><p>format_name</p></td>
<td class="parameter_description"><p>The short name of the image_format (e.g. JPEG or PNG).</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>role</p></td>
<td class="parameter_description"><p>The dialog's <em class="parameter"><code>role</code></em>
which will be set with
<a href="https://developer.gnome.org/gtk3/GtkWindow.html#gtk-window-set-role"><code class="function">gtk_window_set_role()</code></a>.</p></td>
<td class="parameter_annotations"> </td>
</tr>
<tr>
<td class="parameter_name"><p>help_id</p></td>
<td class="parameter_description"><p>The GIMP help id.</p></td>
<td class="parameter_annotations"> </td>
</tr>
</tbody>
</table></div>
</div>
<div class="refsect3">
<a name="gimp-export-dialog-new.returns"></a><h4>Returns</h4>
<p>The new export dialog. </p>
<p><span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span></p>
</div>
<p class="since">Since: <a class="link" href="api-index-2-8.html#api-index-2.8">2.8</a></p>
</div>
<hr>
<div class="refsect2">
<a name="gimp-export-dialog-get-content-area"></a><h3>gimp_export_dialog_get_content_area ()</h3>
<pre class="programlisting"><a href="https://developer.gnome.org/gtk3/GtkWidget.html#GtkWidget-struct"><span class="returnvalue">GtkWidget</span></a> *
gimp_export_dialog_get_content_area (<em class="parameter"><code><a href="https://developer.gnome.org/gtk3/GtkWidget.html#GtkWidget-struct"><span class="type">GtkWidget</span></a> *dialog</code></em>);</pre>
<p>Returns the vertical <a href="https://developer.gnome.org/gtk3/GtkBox.html#GtkBox-struct"><span class="type">GtkBox</span></a> of the passed export dialog to be filled with
export options.</p>
<div class="refsect3">
<a name="gimp-export-dialog-get-content-area.parameters"></a><h4>Parameters</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="parameters_name">
<col class="parameters_description">
<col width="200px" class="parameters_annotations">
</colgroup>
<tbody><tr>
<td class="parameter_name"><p>dialog</p></td>
<td class="parameter_description"><p>A dialog created with <a class="link" href="libgimp3-gimpexport.html#gimp-export-dialog-new" title="gimp_export_dialog_new ()"><code class="function">gimp_export_dialog_new()</code></a></p></td>
<td class="parameter_annotations"> </td>
</tr></tbody>
</table></div>
</div>
<div class="refsect3">
<a name="gimp-export-dialog-get-content-area.returns"></a><h4>Returns</h4>
<p>The <a href="https://developer.gnome.org/gtk3/GtkBox.html#GtkBox-struct"><span class="type">GtkBox</span></a> to fill with export options. </p>
<p><span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></p>
</div>
<p class="since">Since: <a class="link" href="api-index-2-8.html#api-index-2.8">2.8</a></p>
</div>
</div>
<div class="refsect1">
<a name="libgimp3-gimpexport.other_details"></a><h2>Types and Values</h2>
<div class="refsect2">
<a name="GimpExportCapabilities"></a><h3>enum GimpExportCapabilities</h3>
<p>The types of images and layers an export procedure can handle</p>
<div class="refsect3">
<a name="GimpExportCapabilities.members"></a><h4>Members</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="300px" class="enum_members_name">
<col class="enum_members_description">
<col width="200px" class="enum_members_annotations">
</colgroup>
<tbody>
<tr>
<td class="enum_member_name"><p><a name="GIMP-EXPORT-CAN-HANDLE-RGB:CAPS"></a>GIMP_EXPORT_CAN_HANDLE_RGB</p></td>
<td class="enum_member_description">
<p>Handles RGB images</p>
</td>
<td class="enum_member_annotations"> </td>
</tr>
<tr>
<td class="enum_member_name"><p><a name="GIMP-EXPORT-CAN-HANDLE-GRAY:CAPS"></a>GIMP_EXPORT_CAN_HANDLE_GRAY</p></td>
<td class="enum_member_description">
<p>Handles grayscale images</p>
</td>
<td class="enum_member_annotations"> </td>
</tr>
<tr>
<td class="enum_member_name"><p><a name="GIMP-EXPORT-CAN-HANDLE-INDEXED:CAPS"></a>GIMP_EXPORT_CAN_HANDLE_INDEXED</p></td>
<td class="enum_member_description">
<p>Handles indexed images</p>
</td>
<td class="enum_member_annotations"> </td>
</tr>
<tr>
<td class="enum_member_name"><p><a name="GIMP-EXPORT-CAN-HANDLE-BITMAP:CAPS"></a>GIMP_EXPORT_CAN_HANDLE_BITMAP</p></td>
<td class="enum_member_description">
<p>Handles two-color indexed images</p>
</td>
<td class="enum_member_annotations"> </td>
</tr>
<tr>
<td class="enum_member_name"><p><a name="GIMP-EXPORT-CAN-HANDLE-ALPHA:CAPS"></a>GIMP_EXPORT_CAN_HANDLE_ALPHA</p></td>
<td class="enum_member_description">
<p>Handles alpha channels</p>
</td>
<td class="enum_member_annotations"> </td>
</tr>
<tr>
<td class="enum_member_name"><p><a name="GIMP-EXPORT-CAN-HANDLE-LAYERS:CAPS"></a>GIMP_EXPORT_CAN_HANDLE_LAYERS</p></td>
<td class="enum_member_description">
<p>Handles layers</p>
</td>
<td class="enum_member_annotations"> </td>
</tr>
<tr>
<td class="enum_member_name"><p><a name="GIMP-EXPORT-CAN-HANDLE-LAYERS-AS-ANIMATION:CAPS"></a>GIMP_EXPORT_CAN_HANDLE_LAYERS_AS_ANIMATION</p></td>
<td class="enum_member_description">
<p>Handles animation of layers</p>
</td>
<td class="enum_member_annotations"> </td>
</tr>
<tr>
<td class="enum_member_name"><p><a name="GIMP-EXPORT-CAN-HANDLE-LAYER-MASKS:CAPS"></a>GIMP_EXPORT_CAN_HANDLE_LAYER_MASKS</p></td>
<td class="enum_member_description">
<p>Handles layer masks</p>
</td>
<td class="enum_member_annotations"> </td>
</tr>
<tr>
<td class="enum_member_name"><p><a name="GIMP-EXPORT-NEEDS-ALPHA:CAPS"></a>GIMP_EXPORT_NEEDS_ALPHA</p></td>
<td class="enum_member_description">
<p>Needs alpha channels</p>
</td>
<td class="enum_member_annotations"> </td>
</tr>
<tr>
<td class="enum_member_name"><p><a name="GIMP-EXPORT-NEEDS-CROP:CAPS"></a>GIMP_EXPORT_NEEDS_CROP</p></td>
<td class="enum_member_description">
<p>Needs to crop content to image bounds</p>
</td>
<td class="enum_member_annotations"> </td>
</tr>
</tbody>
</table></div>
</div>
</div>
<hr>
<div class="refsect2">
<a name="GimpExportReturn"></a><h3>enum GimpExportReturn</h3>
<p>Possible return values of <a class="link" href="libgimp3-gimpexport.html#gimp-export-image" title="gimp_export_image ()"><code class="function">gimp_export_image()</code></a>.</p>
<div class="refsect3">
<a name="GimpExportReturn.members"></a><h4>Members</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="300px" class="enum_members_name">
<col class="enum_members_description">
<col width="200px" class="enum_members_annotations">
</colgroup>
<tbody>
<tr>
<td class="enum_member_name"><p><a name="GIMP-EXPORT-CANCEL:CAPS"></a>GIMP_EXPORT_CANCEL</p></td>
<td class="enum_member_description">
<p>The export was cancelled</p>
</td>
<td class="enum_member_annotations"> </td>
</tr>
<tr>
<td class="enum_member_name"><p><a name="GIMP-EXPORT-IGNORE:CAPS"></a>GIMP_EXPORT_IGNORE</p></td>
<td class="enum_member_description">
<p>The image is unmodified but export shall continue anyway</p>
</td>
<td class="enum_member_annotations"> </td>
</tr>
<tr>
<td class="enum_member_name"><p><a name="GIMP-EXPORT-EXPORT:CAPS"></a>GIMP_EXPORT_EXPORT</p></td>
<td class="enum_member_description">
<p>The chosen transforms were applied to the image</p>
</td>
<td class="enum_member_annotations"> </td>
</tr>
</tbody>
</table></div>
</div>
</div>
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.33.0</div>
</body>
</html>